Skip to content

feat: add Navigation and OData V4 tutorials, align all packages#295

Open
petermuessig wants to merge 3 commits into
mainfrom
feat/integrate-navigation-odatav4-tutorials
Open

feat: add Navigation and OData V4 tutorials, align all packages#295
petermuessig wants to merge 3 commits into
mainfrom
feat/integrate-navigation-odatav4-tutorials

Conversation

@petermuessig

@petermuessig petermuessig commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

What this PR does

Brings two new tutorials into the monorepo — Navigation and Routing (17 steps) and OData V4 (11 steps) — and reworks all four tutorials onto a single template so they share the same toolchain, layout, namespace, and documentation conventions.

After this PR the repo ships 4 tutorials with 69 step workspaces, all under the ui5.tutorial.<name>.stepNN naming.

Tutorials

packages/navigation/ (new)

  • 17 steps imported from the OpenUI5 demokit, restructured into the standard steps/NN/ layout.
  • App namespace renamed sap.ui.demo.navui5.tutorial.navigation across manifests, TS imports, JSDoc @namespace, XML controllerName, tsconfig paths, and HTML resource-roots.
  • Dev dependencies switched to the walkthrough set (@types/openui5, ui5-middleware-serveframework, ui5-tooling-transpile).
  • Per-step package.json names → ui5.tutorial.navigation.stepNN; ui5.yaml metadata aligned.

packages/odatav4/ (new)

  • 11 steps imported from the same demokit source.
  • Restructured solutions/steps/, root-level markdown moved into per-step README.md, shared images/ split into per-step assets/.
  • JS sources fully converted to TypeScript ES modules: Component, App.controller, model/models, initMockServer, the ~800-line sinon-based mock server, plus the view XML.
  • Hungarian variable prefixes stripped (oModelmodel, aMatchesmatches, sUrlurl, …) to match the project's TS style — confirmed against packages/walkthrough/.
  • App namespace standardised to ui5.tutorial.odatav4.

Namespace alignment of the existing tutorials

  • packages/walkthrough/ — renamed ui5.walkthroughui5.tutorial.walkthrough across ~630 files (manifests, TS imports + @namespace, XML controllerName + xmlns, tsconfig paths, HTML resource-roots, every README code snippet, step package.json names).
  • packages/quickstart/ — renamed ui5.quickstartui5.tutorial.quickstart with the same shape across 27 files; ui5.yaml metadata.name quickstart-tutorialui5.tutorial.quickstart.

Documentation

  • Per-tutorial overview READMEs (packages/{navigation,odatav4}/README.md) now mirror packages/walkthrough/README.md: each step bullet has an inline 🔗 Live Preview link plus paired <details class="ts-only"> / <details class="js-only"> 📥 Download Solution blocks.
  • Step READMEs ship with paired ```ts / ```js code blocks so the Jekyll code-couple toggle renders both flavours. The JS half is generated from the build's sanitised *-dbg.js output where applicable.
  • Folder-structure images replaced with fenced ```text ASCII trees (using .?s placeholders so the toggle flips the extensions); images deleted from per-step assets/.
  • All callout syntaxes (GitHub-flavoured alerts > [!NOTE] plus walkthrough's emoji blockquotes > 📝 **Note:** <br>) normalised to the :note: / :tip: / :info: / :caution: / :warning: shorthand mandated by _/AUTOMATE.md — 76 callouts converted.
  • Step-level "view and download all files at [demokit]" links retargeted to the published https://ui5.github.io/tutorials/... URLs so they resolve against the local dist/ via the dev server.
  • License year bumped 2025 → 2026 across all overview READMEs; ## License sections added to the new navigation and odatav4 overviews.

Tooling

  • tools/dev-server/server.js:
    • Mount dist/ under /dist/... so npm start serves the locally-built apps and ZIPs.
    • Rewrite the published https://ui5.github.io/tutorials/... URLs in rendered markdown to local /dist/... paths for the four known tutorial slugs (walkthrough, quickstart, navigation, odatav4).
    • Friendly hint page when an artifact is missing.
  • README.md: document the npm install && npm run build && npm start workflow.

Verification

  • npm install succeeds and registers all 69 workspaces under the new ui5.tutorial.* namespace.
  • npm run typecheck -ws --if-present → exit 0.
  • npm run build → exit 0. Produces dist/<tutorial>/build/NN/ apps, <tutorial>-step-NN.zip and <tutorial>-step-NN-js.zip downloads, and the rewritten dist/index.md overview for each tutorial.
  • index-cdn.html present for every webapp that bootstraps SAPUI5 (68 of 69 — walkthrough step 01 is the bare HTML "Hello World" and intentionally has none).
  • ✅ Dev-server smoke test: Live Preview links from the overview README resolve to /dist/<tutorial>/build/NN/index-cdn.html with HTTP 200.

Stats

1363 files changed: 49,009 insertions, 1,320 deletions.

JIRA: FIORITECHP1-35769

Bring two new tutorials — Navigation and Routing, OData V4 — into the
monorepo, and rework all four tutorials onto a single template so they
share the same toolchain, layout, namespace, and documentation
conventions.

Tutorials

- packages/navigation/ — 17 steps imported from the OpenUI5 demokit,
  promoted to the standard `steps/` layout, package names changed to
  `ui5.tutorial.navigation.stepNN`, ui5.yaml metadata aligned with the
  rest of the repo, dev dependencies switched to the walkthrough set
  (@types/openui5, ui5-middleware-serveframework, ui5-tooling-transpile),
  app namespace renamed `sap.ui.demo.nav` -> `ui5.tutorial.navigation`
  across manifests, TS imports, JSDoc, XML controllerName, tsconfig
  paths, and HTML resource-roots.

- packages/odatav4/ — 11 steps imported from the same demokit source,
  restructured from `solutions/` -> `steps/`, root-level markdown moved
  into per-step README.md, shared `images/` split into per-step
  `assets/`. JS sources fully converted to TypeScript ES modules
  (Component, App.controller, model/models, initMockServer, the ~800-
  line sinon-based mock server, view XML), Hungarian variable prefixes
  stripped (oModel -> model, aMatches -> matches, sUrl -> url, ...) to
  match the project's TS style. App namespace standardised to
  `ui5.tutorial.odatav4`.

Namespace alignment across the existing tutorials

- packages/walkthrough/ renamed `ui5.walkthrough` -> `ui5.tutorial.walkthrough`
  across ~630 files (manifests, TS imports + @namespace, XML
  controllerName + xmlns, tsconfig paths, HTML resource-roots, every
  README code snippet, step package.json names).
- packages/quickstart/ renamed `ui5.quickstart` -> `ui5.tutorial.quickstart`
  with the same shape across 27 files; ui5.yaml `metadata.name`
  `quickstart-tutorial` -> `ui5.tutorial.quickstart`.

After this commit, all 69 step workspaces follow the same naming
convention: `ui5.tutorial.<tutorial>.stepNN`.

Documentation

- Per-tutorial overview READMEs (packages/{navigation,odatav4}/README.md)
  now mirror packages/walkthrough/README.md: each step bullet has an
  inline `[🔗 Live Preview]` link and paired `<details class="ts-only">` /
  `<details class="js-only">` `[📥 Download Solution]` blocks.
- Step READMEs ship with paired ```ts / ```js code blocks so the
  Jekyll code-couple toggle renders both flavours. JS half generated
  from the build's sanitized `*-dbg.js` output where applicable.
- Folder-structure images replaced with fenced ```text ASCII trees
  (using `.?s` placeholders so the global toggle flips the extensions);
  images deleted from the per-step assets.
- All callout syntaxes (GitHub-flavoured alerts `> [!NOTE]` plus
  walkthrough's emoji blockquotes `> 📝 **Note:** <br>`) normalised to
  the `:note:` / `:tip:` / `:info:` / `:caution:` / `:warning:`
  shorthand mandated by `_/AUTOMATE.md`.
- Step-level "view and download all files at \[demokit\]" links
  retargeted to the published `https://ui5.github.io/tutorials/...`
  URLs so they resolve against the local dist via the dev server.
- License year bumped 2025 -> 2026 across all overview READMEs;
  `## License` sections added to the navigation and odatav4 overviews
  to match the walkthrough/quickstart convention.

Tooling

- tools/dev-server/server.js: mount `dist/` under `/dist/...` so
  `npm start` serves the locally-built apps and ZIPs; rewrite the
  published `https://ui5.github.io/tutorials/...` URLs in rendered
  markdown to the local `/dist/...` paths for the four known tutorial
  slugs (walkthrough, quickstart, navigation, odatav4); friendly hint
  page when an artifact is missing.
- README.md: document the `npm install && npm run build && npm start`
  workflow.

Verification

- `npm install` succeeds and registers all 69 workspaces under the new
  `ui5.tutorial.*` namespace.
- `npm run typecheck -ws --if-present` exits 0.
- `npm run build` exits 0; produces `dist/<tutorial>/build/NN/` apps,
  `<tutorial>-step-NN.zip` and `<tutorial>-step-NN-js.zip` downloads,
  and the rewritten `dist/index.md` overview for each tutorial.
- `index-cdn.html` present for every webapp that bootstraps SAPUI5
  (68 of 69 — walkthrough step 01 is the bare HTML "Hello World" and
  intentionally has none).
- Dev-server smoke test: Live Preview links from the overview README
  resolve to `/dist/<tutorial>/build/NN/index-cdn.html` with HTTP 200.
Comment thread packages/odatav4/steps/01/webapp/view/App.view.xml Outdated
Comment thread packages/odatav4/steps/01/webapp/manifest.json Outdated
Comment thread packages/odatav4/steps/01/ui5.yaml Outdated
Versions
- Bump framework to OpenUI5 1.148.1 (latest LTS patch) in every step
  ui5.yaml and CDN bootstrap URL.
- Bump manifest _version to 2.8.0 and minUI5Version to 1.148 across
  all 69 manifests (mapping per UI5/manifest v2/mapping.json).
- specVersion: "4.0" for every ui5.yaml.
- @types/openui5 ^1.148.0 in every step package.json.
- Sync README narrative and inline manifest snippets that referenced
  OpenUI5 1.120 / _version 1.60.0 / 1.38.0 to the new values.

Reviewer findings (PR #295, @flovogt)
- Manifest v2 (_version 2.8.0).
- specVersion '4.0'.
- Ensure trailing newline on every webapp source file.

Cross-tutorial inconsistency cleanup
- Quickstart Component.ts: @namespace sap.m.tutorial.quickstart.NN
  -> ui5.tutorial.quickstart, switch to public static metadata and
  add interfaces: ["sap.ui.core.IAsyncContentCreation"].
- Strip residual Hungarian-notation in quickstart controllers/index.ts
  (oEvent/bState/oView) and the named identifiers in odatav4 OPA tests
  (iGrowingBy/sViewName/oListBinding).
- Add explicit "strict": false, "strictNullChecks": false to walkthrough
  and quickstart tsconfig.json files (match navigation/odatav4).
- Drop redundant data-sap-ui-libs from quickstart steps 02 and 03
  index.html (Component manifest already declares the libs).
- Add data-sap-ui-theme="sap_horizon" to quickstart and navigation
  bootstrap script tags so the theme is explicit and consistent with
  walkthrough/odatav4.

Indentation normalization per .editorconfig
- JSON / XML / YAML / .properties -> 2 spaces.
- TS / JS / HTML -> tabs.
- Re-indent fenced code blocks inside step README.md files to match
  the same conventions so doc snippets mirror the actual source files.

Verified: npm run typecheck and npm run build both exit 0; ui5-linter
clean on sampled steps; manifest validation clean.
@petermuessig

Copy link
Copy Markdown
Contributor Author

@flovogt thanks for the review — all three findings are addressed in 9b4f266, plus a broader cleanup pass on cross-tutorial inconsistencies that showed up once versions were aligned. Threads resolved above.

Review findings ✅

  • manifest v2_version: "2.8.0" across all 69 manifests (mapping for UI5 1.148 per ui5-manifest mapping.json)
  • specVersion '4.0'specVersion: "4.0" in all 69 ui5.yaml files
  • Trailing newlines → every webapp source file ends with \n (re-checked after the indent sweep)

UI5 LTS alignment

  • Framework bumped to OpenUI5 1.148.1 (latest patch in the 1.148.x LTS line) in every step ui5.yaml, every CDN bootstrap URL (index-cdn.html and walkthrough's test/*.cdn.qunit.html / mockServer-cdn.html), and @types/openui5^1.148.0
  • minUI5Version"1.148" in every manifest
  • README narrative and inline manifest snippets that referenced the previous LTS (1.120 / _version 1.60.0 / 1.38.0) updated to the new values

Cross-tutorial cleanup

  • Quickstart Component.ts: @namespace sap.m.tutorial.quickstart.NNui5.tutorial.quickstart, static readonly metadatapublic static metadata, added missing interfaces: ["sap.ui.core.IAsyncContentCreation"]
  • Hungarian-notation residue stripped in quickstart controllers/index.ts (oEvent/bState/oView) and the three identifiers named in the odatav4 OPA tests (iGrowingBy/sViewName/oListBinding)
  • tsconfig.json: explicit "strict": false, "strictNullChecks": false added to walkthrough and quickstart tsconfigs to match navigation/odatav4
  • index.html: removed redundant data-sap-ui-libs from quickstart steps 02/03 (Component manifest already declares the libs); added explicit data-sap-ui-theme="sap_horizon" to quickstart and navigation bootstrap tags

Indentation normalization per .editorconfig

  • JSON / XML / YAML / .properties → 2 spaces
  • .ts / .js / .html → tabs
  • Fenced code blocks inside step README.md files re-indented to the same conventions, so the doc snippets mirror the actual source files byte-for-byte

Per-tutorial differences kept intentional: per-tutorial framework.libraries, walkthrough's simpleproxy for OData V2 (only used by that tutorial), walkthrough's @ui5/ts-interface-generator/local-web-server/build-script late-step extras, odatav4's SAP i18n comment prefixes (#XTIT:/#XFLD: …) and // filename.ts — headers, and the controller-folder layout in quickstart (kept flat at webapp/ for tutorial simplicity).

Verification

  • npm run typecheck → exit 0 across all 69 workspaces
  • npm run build → exit 0; dist/ regenerated cleanly with the new framework version
  • ui5-linter (via UI5 MCP) → 0 findings on sampled steps in all four tutorials
  • run_manifest_validation clean on navigation step 01; the contentDensities schema-strictness warnings surfaced on other manifests (e.g. odatav4/01, walkthrough/15) are an orthogonal item we can address in a follow-up if you'd like.

@petermuessig petermuessig requested review from akudev and flovogt June 30, 2026 16:51
Comment thread packages/navigation/steps/01/package.json
Replace deprecated @types/openui5 package with the official @openui5/types
package across all tutorial packages and steps. Updates include:

- package.json: @types/openui5 → @openui5/types in devDependencies
- tsconfig.json: Updated types array entries
- README.md: Updated documentation references

This aligns with the OpenUI5 project's official type definitions package.
@petermuessig

Copy link
Copy Markdown
Contributor Author

Latest commit: Migrated from @types/openui5 to @openui5/types

The package reference for OpenUI5 TypeScript types has been updated across all tutorial packages to use the official @openui5/types package instead of the deprecated @types/openui5.

Changes

  • package.json: Replaced @types/openui5 with @openui5/types in devDependencies across all steps of all tutorials (quickstart, walkthrough, navigation, odatav4)
  • tsconfig.json: Updated the types array entries accordingly
  • README.md: Updated documentation references in quickstart step 1, walkthrough steps 2 and 3

Scope

138 files updated across the following packages:

  • packages/quickstart (steps 1–3)
  • packages/walkthrough (steps 2–38)
  • packages/navigation (steps 1–17)
  • packages/odatav4 (steps 1–11)

@petermuessig petermuessig requested a review from flovogt July 1, 2026 09:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants